<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Context Policy</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link href="theme/style.css" rel="stylesheet" type="text/css">
<style type="text/css">
.style1 {
	background-color: #EEEEEE;
}
</style>
</head>
<body>
<table background="theme/bkd2.gif" border="0" cellspacing="2" width="100%">
  <tbody>
    <tr>
      <td width="21">&nbsp;</td>
      <td width="885"><font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>The 
        Context Policy </b></font></td>
      <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" align="right" border="0" height="68" width="93"></a></td>
    </tr>
  </tbody>
</table>
<br>
<table border="0">
  <tbody>
    <tr>
      <td width="10"></td>
      <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
      <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/l_arr.gif" border="0" height="19" width="20"></a></td>
      <td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td>
    </tr>
  </tbody>
</table>
<blockquote>
  <p><a href="class_reference_ctxpolicy.html#introduction">Introduction</a><br>
    <a href="class_reference_ctxpolicy.html#header_synopsis">Header 'wave/preprocessing_hooks.hpp' 
    synopsis</a><br>
    <a href="class_reference_ctxpolicy.html#member_functions">Member functions</a></p>
</blockquote>
<h2><b><a name="introduction"></a>Introduction</b></h2>
<p>The context policy is used to provide callback hooks, which are called from inside the library into the user code, whenever</p>
<ul>
  <li>a preprocessor directive has been recognized (or <b>not</b> recognized), </li>
  <li>a token is about to be returned from the preprocessor, </li>
  <li>a macro gets defined or undefined, </li>
  <li>a macro has been expanded or rescanned,</li>
  <li>a <span class="preprocessor">#line</span> directive is emitted,</li>
  <li>an include file is searched for in the filesystem,</li>
  <li>an include file has been opened or closed, </li>
  <li>a conditional expression was evaluated,</li>
  <li>a token has to be skipped because it is contained in a non-evaluated conditional block, or</li>
  <li>a pragma of the form <tt>'wave option[(value)]'</tt> has been recognized. </li>
</ul>
<p>This policy type is used as a template parameter to the <a href="class_reference_context.html"><tt>boost::wave::context&lt;&gt;</tt></a> object, where the default policy provides empty hook functions only.</p>
<h2><a name="header_synopsis"></a>Header <a href="http://svn.boost.org/trac/boost/browser/trunk/boost/wave/preprocessing_hooks.hpp">wave/preprocessing_hooks.hpp</a> synopsis</h2>
<pre><span class="keyword">namespace</span> boost {<br><span class="keyword">namespace</span> wave {<br><span class="keyword">namespace</span> context_policies {<br> <br>    <span class="keyword">struct</span> default_preprocessing_hooks {<br><br>        <span class="comment">// general hook functions</span>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>        <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_directive">found_directive</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            TokenT <span class="keyword">const </span>&amp;directive);<br>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> <span class="type">ContextT</span>, <span class="keyword">typename</span> <span class="type">ContainerT</span>&gt;
        <span class="type">bool</span> <a href="class_reference_ctxpolicy.html#found_unknown_directive">found_unknown_directive</a>(<span class="type">ContextT</span> <span class="keyword">const</span>&amp; <span class="variable-name">ctx</span>,
            <span class="type">ContainerT</span> <span class="keyword">const</span>&amp; <span class="variable-name">line</span>, <span class="type">ContainerT</span>&amp; <span class="variable-name">pending</span>);
</span>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ExceptionT&gt;<br>        void <a href="class_reference_ctxpolicy.html#throw_exception">throw_exception</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            ExceptionT <span class="keyword">const</span>&amp; e);<br><br>        <span class="comment">// test, whether a given token may be skipped</span><br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;<br>        <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#may_skip_whitespace">may_skip_whitespace</a> (ContextT <span class="keyword">const</span>&amp; ctx,<br>            TokenT &amp;token, <span class="keyword">bool</span> &amp;skipped_newline);<br>

        <span class="comment">// Conditional compilation</span><span class="keyword">
        template</span> &lt;<br>            <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <br>            <span class="keyword">typename</span> ContainerT<br>        &gt;<br>        <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#evaluated_conditional_expression">evaluated_conditional_expression</a>(<br>            ContextT <span class="keyword">const</span> &amp;ctx, TokenT <span class="keyword">const</span>&amp; directive, <br>            ContainerT <span class="keyword">const</span>&amp; expression, <span class="keyword">bool</span> expression_value);<br>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>            <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#skipped_token">skipped_token</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            TokenT <span class="keyword">const</span>&amp; token);<br><br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>        TokenT <span class="keyword">const</span>&amp; <a href="class_reference_ctxpolicy.html#generated_token">generated_token</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            TokenT <span class="keyword">const</span>&amp; token);<br><br><br>        <span class="comment">// macro expansion tracing</span><span class="keyword">
        template</span> &lt;<span class="keyword">
            typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT,<br>            <span class="keyword">typename</span> IteratorT<br>        &gt;<br>        <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#expanding_function_like_macro">expanding_function_like_macro</a>(<br>            ContextT <span class="keyword">const</span> &amp;ctx, TokenT <span class="keyword">const</span> &amp;macrodef, <br>            <span class="keyword">std::vector</span>&lt;TokenT&gt; <span class="keyword">const</span> &amp;formal_args, <br>            ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall, <br>            <span class="keyword">std::vector</span>&lt;ContainerT&gt; <span class="keyword">const</span> &amp;arguments,<br>            IteratorT <span class="keyword">const</span> &amp;seqstart, Iterator <span class="keyword">const</span> &amp;seqend);<br> <br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;<br>        <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#expanding_object_like_macro">expanding_object_like_macro</a>(<br>            ContextT <span class="keyword">const</span> &amp;ctx, TokenT <span class="keyword">const</span> &amp;macro, <br>            ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall);<br> <br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#expanded_macro">expanded_macro</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            ContainerT <span class="keyword">const</span> &amp;result);<br> <br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#expanded_macro">rescanned_macro</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            ContainerT <span class="keyword">const</span> &amp;result);<br><br>
        <span class="comment">// include file tracing functions</span>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;<br>        <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#opened_include_file">found_include_directive</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            std::string <span class="keyword">const</span> &amp;filename, <span class="keyword">bool</span> include_next);<br>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> <span class="type">ContextT</span>&gt;
        <span class="type">bool</span> <a href="class_reference_ctxpolicy.html#locate_include_file">locate_include_file</a>(<span class="type">ContextT</span>&amp; <span class="variable-name">ctx</span>, <span class="constant">std</span>::<span class="type">string</span> &amp;<span class="variable-name">file_path</span>, 
            <span class="type">bool</span> <span class="variable-name">is_system</span>, <span class="type">char</span> <span class="keyword">const</span> *<span class="variable-name">current_name</span>,
            <span class="constant">std</span>::<span class="type">string</span> &amp;<span class="variable-name">dir_path</span>, <span class="constant">std</span>::<span class="type">string</span> &amp;<span class="variable-name">native_name</span>);<br>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;<br>        <span class="keyword">void </span><a href="class_reference_ctxpolicy.html#opened_include_file">opened_include_file</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            std::string <span class="keyword">const</span> &amp;relname, std::string <span class="keyword">const</span>&amp; absname,<br>            <span class="keyword">bool</span> is_system_include); <br>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;<br>        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#returning_from_include_file">returning_from_include_file</a>(ContextT <span class="keyword">const</span> &amp;ctx);<br>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;<br>        <span class="keyword">void</span> <a href="#detected_include_guard">detected_include_guard</a>(ContextT <span class="keyword">const</span> &amp;ctx, 
            std::string <span class="keyword">const</span>&amp; filename,
            std::string <span class="keyword">const</span>&amp; include_guard);<br>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>        <span class="keyword">void</span> <a href="#detected_pragma_once">detected_pragma_once</a>(ContextT <span class="keyword">const</span> &amp;ctx,
            TokenT <span class="keyword">const</span>&amp; pragma_token, 
            std::string <span class="keyword">const</span>&amp; filename);<br><br>
        <span class="comment">// interpretation of #pragmas of the form </span>
        <span class="comment">// 'wave option[(value)]'</span>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>        <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#interpret_pragma">interpret_pragma</a>(ContextT <span class="keyword">const</span> &amp;ctx, ContainerT &amp;pending, <br>            <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &amp;option, <br>            ContainerT <span class="keyword">const</span> &amp;values, <br>            <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &amp;pragma_token);<br><br>
        <span class="comment">// macro definition hooks</span>
        <span class="keyword">template</span> &lt;<br>            <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">
            typename</span> ParametersT, <span class="keyword">typename</span> DefinitionT<br>        &gt;<br>        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#defined_macro">defined_macro</a>(ContextT <span class="keyword">const</span> &amp;ctx, TokenT <span class="keyword">const</span> &amp;name, <span class="keyword">
            bool</span> is_functionlike, ParametersT <span class="keyword">const</span> &amp;parameters, <br>            DefinitionT <span class="keyword">const</span> &amp;definition, <span class="keyword">bool</span> is_predefined);<br><br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#undefined_macro">undefined_macro</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            TokenT<span class="keyword"> const</span> &amp;name);<br><br>
        <span class="comment">// #error and #warning directive hooks</span>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>        <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_warning_directive">found_warning_directive</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            ContainerT <span class="keyword">const</span> &amp;message);<br><br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>        <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_error_directive">found_error_directive</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            ContainerT <span class="keyword">const</span> &amp;message);<br><br>        <span class="comment">// #line directive hooks</span>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#found_line_directive">found_line_directive</a>(ContextT <span class="keyword">const</span> &amp;ctx, <br>            ContainerT <span class="keyword">const</span> &amp;arguments, <span class="keyword">unsigned int</span> line,<br>            std::string <span class="keyword">const</span>&amp; filename);<br>
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> <span class="type">ContextT</span>, <span class="keyword">typename</span> <span class="type">ContainerT</span>&gt;
        <span class="type">bool</span> <a href="class_reference_ctxpolicy.html#emit_line_directive">emit_line_directive</a>(<span class="type">ContextT</span> <span class="keyword">const</span>&amp; <span class="variable-name">ctx</span>, <span class="type">ContainerT</span> &amp;<span class="variable-name">pending</span>, 
            <span class="keyword">typename</span> <span class="constant">ContextT</span>::<span class="type">token_type</span> <span class="keyword">const</span>&amp; <span class="variable-name">act_token</span>);

    };<br><br>}}}   <span class="comment">// namespace boost::wave::context_policies</span></pre>
<h2><a name="member_functions"></a>Member functions</h2>
<h3>General hook functions </h3>
<p><a name="found_directive"></a><strong>found_directive</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>    <span class="keyword">bool</span> found_directive(ContextT <span class="keyword">const</span>&amp; ctx, TokenT <span class="keyword">const </span>&amp;directive);
</pre>
<blockquote>
  <p>The function <tt>found_directive</tt> is called, whenever the preprocessor has detected one of the preprocessing directives (<span class="preprocessor">#define</span>, <span class="preprocessor">#undef</span>, <span class="preprocessor">#if</span>, <span class="preprocessor">#idef</span>, <span class="preprocessor">#ifndef</span>, <span class="preprocessor">#elif</span>, <span class="preprocessor">#endif</span>, <span class="preprocessor">#error</span>, <span class="preprocessor">#include</span>, <span class="preprocessor">#pragma</span> or <span class="preprocessor">#warning</span>) .</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The parameter <tt>directive</tt> refers to the token containing the detected preprocessing directive. </p>
  <p>If the return value is <tt>true</tt>, the directive will be
    skipped altogether, i.e. no preprocessing is done. The overall
    directive is replaced by a single newline character. If the return
    value is <tt>false</tt>, the directive is processed in the normal manner. </p>
</blockquote>

<p><a name="found_unknown_directive"></a><strong>found_unknown_directive</strong></p>
<pre>
    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> <span class="type">ContextT</span>, <span class="keyword">typename</span> <span class="type">ContainerT</span>&gt;
    <span class="type">bool</span> <span class="function-name">found_unknown_directive</span>(<span class="type">ContextT</span> <span class="keyword">const</span>&amp; <span class="variable-name">ctx</span>,
        <span class="type">ContainerT</span> <span class="keyword">const</span>&amp; <span class="variable-name">line</span>, <span class="type">ContainerT</span>&amp; <span class="variable-name">pending</span>);
</pre>
<blockquote>
  <p>The function &nbsp;<tt>found_unknown_directive</tt> is called, whenever an unknown preprocessor directive was encountered.</p>
  <p>The parameter &nbsp;<tt>ctx</tt> is a reference to the context object used for instantiating the preprocessing iterators by the user.</p>
  <p>The parameter &nbsp;<tt>line</tt> holds the tokens of the entire source line containing the unknown directive.</p>
  <p>The parameter &nbsp;<tt>pending</tt> may be used to push tokens back into the input stream, which are to be used as the replacement text for the whole line containing the unknown directive.</p>
  <p>The return value defines whether the given expression has been properly interpreted by the hook function or not. If this function returns &nbsp;<tt>false</tt>, the library will raise an &nbsp;<tt>ill_formed_directive</tt> exception. Otherwise the tokens pushed back into &nbsp;<tt>pending</tt> are passed on to the user program.</p>
</blockquote>

<p><a name="throw_exception"></a><strong>throw_exception</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ExceptionT&gt;<br>    void throw_exception(ContextT <span class="keyword">const</span> &amp;ctx, <br>        ExceptionT <span class="keyword">const</span>&amp; e);</pre>
<blockquote>
  <p>The function&nbsp;<tt>throw_exception</tt> is called, whenever a preprocessing exception occurs .</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.&nbsp; </p>
  <p>The parameter&nbsp;<tt>e</tt> is the exception object containing detailed error information. </p>
</blockquote>
<p><a name="may_skip_whitespace" id="may_skip"></a><strong>may_skip_whitespace</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>    <span class="keyword">bool</span> may_skip_whitespace(ContextT <span class="keyword">const</span>&amp; ctx, TokenT &amp;token, <br>        <span class="keyword">bool</span>&amp; skipped_newline);
</pre>
<blockquote>
  <p>The function <tt>may_skip_whitespace</tt> will be called by the library, whenever a token is about to be returned to the calling application. </p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.
    Note, this parameter was added for the Wave V1.2.4 release. </p>
  <p>The <tt>token</tt> parameter holds a reference to the current token. The policy is free to change this token if needed.</p>
  <p>The <tt>skipped_newline</tt> parameter holds a reference to a
    boolean value which should be set to true by the policy function
    whenever a newline is going to be skipped. </p>
  <p>If the return value is <tt>true</tt>, the given token is skipped and the preprocessing continues to the next token. If the return value is <tt>false</tt>, the given token is returned to the calling application. Caution has to be used, because by returning <span class="keyword">true</span> the policy function is able to force skipping even significant tokens not only whitespace. </p>
</blockquote>
<h3>Conditional compilation hook functions </h3>
<p><a name="evaluated_conditional_expression"></a><strong>evaluated_conditional_expression</strong></p>
<pre><span class="keyword">   template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
<span class="keyword">    bool</span> evaluated_conditional_expression(ContextT <span class="keyword">const</span>&amp; ctx, <br>        TokenT <span class="keyword">const</span>&amp; directive, ContainerT <span class="keyword">const</span>&amp; expression, <span class="keyword"><br>        bool</span> expression_value);
</pre>
<blockquote>
  <p>The function <tt>evaluated_conditional_expression</tt> is called, whenever the preprocessor has encountered a <span class="preprocessor">#if</span>, <span class="preprocessor">#elif</span>, <span class="preprocessor">#ifdef</span> or <span class="preprocessor">#ifndef</span> directive. This hook gets passed the non-expanded conditional
    expression (as it was given in the analysed source file) and the result
    of the evaluation of this expression in the current preprocessing
    context.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The <tt>token</tt> parameter holds a reference to the evaluated directive token.&nbsp;</p>
  <p>The parameter <tt>expression</tt> holds the non-expanded token sequence 
    comprising the evaluated expression.</p>
  <p>The parameter <tt>expression_value</tt> contains the result of the evaluation of 
    the expression in the current preprocessing context. </p>
  <p>The return value defines, whether the given expression has to be
    evaluated again, allowing to decide which of the conditional branches
    should be expanded. You need to return '<span class="keyword">true</span>' from this hook function to force the expression to be re-evaluated. <br>
  </p>
</blockquote>
<p><a name="skipped_token"></a><strong>skipped_token</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>    <span class="keyword">void</span> skipped_token(ContextT <span class="keyword">const</span>&amp; ctx, TokenT <span class="keyword">const</span>&amp; token);
</pre>
<blockquote>
  <p>The function <tt>skipped_token</tt> is called, whenever a token is about to be skipped due to a false preprocessor condition (code fragments to be
    skipped inside the not evaluated conditional <span class="preprocessor">#if</span>/<span class="preprocessor">#else</span>/<span class="preprocessor">#endif</span> branches).</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The parameter <tt>token</tt> refers to the token to be skipped.</p>
</blockquote>
<p><a name="generated_token"></a><strong>generated_token</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>    TokenT <span class="keyword">const</span>&amp; generated_token(ContextT <span class="keyword">const</span>&amp; ctx, TokenT <span class="keyword">const</span>&amp; token);
</pre>
<blockquote>
  <p>The function <tt>generated_token</tt> is called, whenever a token is about to be returned from the library.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The parameter <tt>token</tt> refers to the token about to be
    returned from the library. This function may alter the token, but in
    this case it must be implemented with a non-const reference for the
    token parameter, allowing to modify the token in place.</p>
  <p>The default behavior is to return the passed token reference unchanged to the caller.</p>
</blockquote>
<h3>Macro expansion tracking functions</h3>
<p><a name="expanding_function_like_macro"></a><b>expanding_function_like_macro</b></p>
<pre><span class="keyword">   template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;<br>    <span class="keyword">bool</span> expanding_function_like_macro(<br>        ContextT <span class="keyword">const</span>&amp; ctx, TokenT <span class="keyword">const</span> &amp;macrodef, <br>        <span class="keyword">std::vector</span>&lt;TokenT&gt; <span class="keyword">const</span> &amp;formal_args, <br>        ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall, <br>        <span class="keyword">std::vector</span>&lt;ContainerT&gt; <span class="keyword">const</span> &amp;arguments,<br>        IteratorT <span class="keyword">const</span> &amp;seqstart, Iterator <span class="keyword">const</span> &amp;seqend);</pre>
<blockquote>
  <p>The function <tt>expanding_function_like_macro</tt> is called, whenever a 
    function-like macro is to be expanded, i.e. <i>before</i> the actual expansion 
    starts.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The <tt>macroname</tt> parameter marks the position where the macro to expand 
    is defined. It contains the token which identifies the macro name used inside 
    the corresponding macro definition.</p>
  <p>The <tt>formal_args</tt> parameter holds the formal arguments used during 
    the definition of the macro. </p>
  <p>The <tt>definition</tt> parameter holds the macro definition for the macro 
    to trace. This is a standard STL container which holds the token sequence 
    identified during the macro definition as the macro replacement list.</p>
  <p>The <tt>macrocall</tt> parameter marks the position where this macro is invoked. 
    It contains the token, which identifies the macro call inside the preprocessed 
    input stream. </p>
  <p>The <tt>arguments</tt> parameter holds the macro arguments used during the 
    invocation of the macro. This is a vector of standard STL containers which 
    contain the token sequences identified at the position of the macro call as 
    the arguments to be used during the macro expansion. </p>
  <p>The parameters <tt>seqstart</tt> and <tt>seqend</tt> point into the input token 
    stream allowing to access the whole token sequence comprising the macro
    invocation (starting with the opening parenthesis and ending after the 
    closing one).</p>
  <p>If the return value is <tt>true</tt>, the macro is not expanded,
    i.e. the overall macro invocation sequence, including the parameters
    are copied to the output without further processing . If the return
    value is <tt>false</tt>, the macro is expanded as expected. <br>
  </p>
</blockquote>
<p><a name="expanding_object_like_macro"></a><b>expanding_object_like_macro</b></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;<br>    <span class="keyword">bool</span> expanding_object_like_macro(<br>        ContextT <span class="keyword">const</span>&amp; ctx, TokenT <span class="keyword">const</span> &amp;macro, <br>        ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall);
</pre>
<blockquote>
  <p>The function <tt>expanding_object_like_macro</tt> is called, whenever a object-like 
    macro is to be expanded, i.e. <i>before</i> the actual expansion starts.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The <tt>macroname</tt> parameter marks the position where the macro to expand 
    is defined. It contains the token which identifies the macro name used inside 
    the corresponding macro definition.</p>
  <p> The <tt>definition</tt> parameter holds the macro definition for the macro 
    to trace. This is a standard STL container which holds the token sequence 
    identified during the macro definition as the macro replacement list.</p>
  <p>The <tt>macrocall</tt> parameter marks the position where this macro is invoked. 
    It contains the token which identifies the macro call inside the preprocessed 
    input stream. </p>
  <p>If the return value is <tt>true</tt>, the macro is not expanded, i.e. the macro symbol is copied to the output without further processing. If the return value is <tt>false</tt>, the macro is expanded as expected. <br>
  </p>
</blockquote>
<p><a name="expanded_macro"></a><b>expanded_macro</b></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>    <span class="keyword">void</span> expanded_macro(ContextT <span class="keyword">const</span>&amp; ctx, ContainerT <span class="keyword">const</span> &amp;result);
</pre>
<blockquote>
  <p>The function <tt>expanded_macro</tt> is called whenever the expansion of 
    a macro is finished, the replacement list is completely scanned and the identified 
    macros herein are replaced by its corresponding expansion results, but <i>before</i> the rescanning process starts.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The parameter <tt>result</tt> contains the the result of the macro expansion 
    so far. This is a standard STL container containing the generated token sequence.</p>
</blockquote>
<p><a name="rescanned_macro"></a><b>rescanned_macro</b></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>    <span class="keyword">void</span> rescanned_macro(ContextT <span class="keyword">const</span>&amp; ctx, ContainerT <span class="keyword">const</span> &amp;result);
</pre>
<blockquote>
  <p>The function <tt>rescanned_macro</tt> is called whenever the rescanning 
    of a macro is finished, i.e. the macro expansion is complete.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The parameter <tt>result</tt> contains the the result of the whole macro 
    expansion. This is a standard STL container containing the generated token 
    sequence.</p>
</blockquote>
<h3>Include file tracing functions</h3>
<p><a name="opened_include_file" id="found_include_directive"></a><strong>found_include_directive</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;<br>    <span class="keyword">bool</span> found_include_directive(ContextT <span class="keyword">const</span>&amp; ctx, <br>        std::string <span class="keyword">const</span> &amp;filename, <span class="keyword">bool</span> include_next);
</pre>
<blockquote>
  <p>The function <tt>found_include_directive</tt> is called whenever whenever a #include directive was located..</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The parameter <tt>filename</tt> contains the (expanded) file name found after 
    the <span class="preprocessor">#include</span> directive. This has the format <tt>&lt;file&gt;</tt>, <tt>"file"</tt> or <tt>file</tt>. 
    The formats <tt>&lt;file&gt;</tt> or <tt>"file"</tt> are used for <span class="preprocessor">#include</span> directives found 
    in the preprocessed token stream, the format <tt>file</tt> is used for files
    specified through the --force_include command line argument.</p>
  <p>The parameter <tt>include_next</tt> is set to true if the found directive was
    a <span class="preprocessor">#include_next</span> directive and the <tt>BOOST_WAVE_SUPPORT_INCLUDE_NEXT</tt> preprocessing constant was defined to something != 0.</p>
  <p>If the return value is <tt>true</tt>, the include directive is not
    executed, i.e. the file to include is not loaded nor processed. The
    overall directive is replaced by a single newline character. If the
    return value is <tt>false</tt>, the directive is executed in a normal manner. <br>
  </p>
</blockquote>
<p><a name="locate_include_file" id="locate_include_file"></a><strong>locate_include_file</strong></p>
<pre>
    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> <span class="type">ContextT</span>&gt;
    <span class="type">bool</span> <span class="function-name">locate_include_file</span>(<span class="type">ContextT</span>&amp; <span class="variable-name">ctx</span>, <span class="constant">std</span>::<span class="type">string</span> &amp;<span class="variable-name">file_path</span>, 
        <span class="type">bool</span> <span class="variable-name">is_system</span>, <span class="type">char</span> <span class="keyword">const</span> *<span class="variable-name">current_name</span>, <span class="constant">std</span>::<span class="type">string</span> &amp;<span class="variable-name">dir_path</span>, 
        <span class="constant">std</span>::<span class="type">string</span> &amp;<span class="variable-name">native_name</span>)
</pre>
<blockquote>
  <p>The function &nbsp;<tt>locate_include_file</tt> is called, whenever a <span class="preprocessor">#include</span>
directive was encountered. It is supposed to locate the given file and
should return the full file name of the located file. This file name
is expected to uniquely identify the referenced file.</p>

<p>The parameter &nbsp;<tt>ctx</tt> is a reference to the context object used for
instantiating the preprocessing iterators by the user.</p>

<p>The parameter &nbsp;<tt>file_path</tt> contains the (expanded) file name found after
  the <tt>#include</tt> directive. This parameter holds the string as it is
  specified in the <span class="preprocessor">#include</span> directive, i.e. <tt>&lt;file&gt;</tt> or <tt>"file"</tt> will result
  in a parameter value 'file'.</p>

<p>The parameter &nbsp;<tt>is_system</tt> is set to &nbsp;<tt>true</tt> if this call happens as a
  result of a <span class="preprocessor">#include &lt;file&gt;</span> directive, it is &nbsp;<tt>false</tt> otherwise, i.e.
  for <span class="preprocessor">#include "file"</span> directives.</p>

<p>The parameter &nbsp;<tt>current_name</tt> is only used if a <span class="preprocessor">#include_next</span> directive
  was encountered (and <tt>BOOST_WAVE_SUPPORT_INCLUDE_NEXT</tt> was defined to be
non-zero). In this case it points to unique full name of the current
  include file (if any). Otherwise this parameter is set to <tt>NULL</tt>.</p>

<p>The parameter &nbsp;<tt>dir_path</tt> on return is expected to hold the directory
  part of the located file.</p>

<p>The parameter &nbsp;<tt>native_name</tt> on return is expected to hold the unique
  full file name of the located file.</p>

<p>The return value defines whether the file was located successfully.</p>

</blockquote>


<p><a name="opened_include_file" id="opened_include_file"></a><strong>opened_include_file</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;<br>    <span class="keyword">void</span> opened_include_file(ContextT <span class="keyword">const</span>&amp; ctx, <br>        std::string <span class="keyword">const</span> &amp;rel_filename, std::string <span class="keyword">const</span> &amp;abs_filename, <br>        <span class="keyword">bool</span> is_system_include);
</pre>
<blockquote>
  <p>The function <tt>opened_include_file</tt> is called whenever a file referred 
    by an <span class="preprocessor">#include</span> directive was successfully located and opened.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The parameter <tt>rel_filename</tt> contains the (normalised)
    probably relative file system path of the opened file. The concrete
    format of this file name depends on the format of the include search
    path given to the library beforehand.</p>
  <p>The parameter <tt>abs_filename</tt> contains the (normalised) full file system path of the 
    opened file.</p>
  <p>The <tt>is_system_include</tt> parameter denotes, if the given file was found 
    as a result of a <tt>#include&nbsp;&lt;...&gt;</tt> directive.</p>
</blockquote>
<p><a name="returning_from_include_file" id="returning_from_include_file"></a><strong>returning_from_include_file</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;<br>    <span class="keyword">void</span> returning_from_include_file(ContextT <span class="keyword">const</span>&amp; ctx);
</pre>
<blockquote>
  <p>The function <tt>returning_from_include_file</tt> is called whenever an 
    included file is about to be closed after it's processing is complete.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
</blockquote>
<p><a name="detected_include_guard" id="detected_include_guard"></a><strong>detected_include_guard</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;<br>    <span class="keyword">void</span> detected_include_guard(ContextT <span class="keyword">const</span>&amp; ctx, 
        std::string <span class="keyword">const</span>&amp; filename,
        std::string <span class="keyword">const</span>&amp; include_guard);
</pre>
<blockquote>
  <p>The function <tt>detected_include_guard</tt> is called whenever a<span lang="de">n</span> 
  include file is about to be added to the list of #pragma once headers as the 
  result of a detected include guard scheme. That means this header file will 
  not be opened and parsed again even if it is specified in a later
  <span class="preprocessor">#include</span> directive.&nbsp; </p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> 
  used during instantiation of the preprocessing iterators by the user. </p>
	<p>The parameter <tt>filename</tt> contains the file system path of the opened file 
	(this is relative to the directory of the currently processed file or a 
	absolute path depending on the paths given as the include search paths).</p>
	<p>The parameter <tt>include_guard</tt> contains the name of the detected include guard.<br> </p>
</blockquote>
<p><a name="detected_pragma_once" id="detected_pragma_once"></a><strong>detected_pragma_once</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename </span>TokenT&gt;<br>    <span class="keyword">void</span> detected_<span lang="de">p<span class="style1">ragma<span lang="en-us">_</span>once</span></span>(ContextT <span class="keyword">const</span>&amp; ctx,
<span lang="de">        TokenT <span class="keyword">const</span>&amp; pragma_token,</span>
        std::string <span class="keyword">const</span>&amp; filename);</pre>
<blockquote>
  <p>The function <tt>detected_pragma_once</tt> is called whenever either a<span lang="de">n</span> 
  include file is about to be added to the list of #pragma once headers as the 
  result of a detected <span lang="de"><span class="preprocessor">#pragma once</span> 
  directive</span>. That means this header file will not be opened and parsed 
  again even if it is specified in a later <span class="preprocessor">#include</span> 
  directive. </p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> 
  used during instantiation of the preprocessing iterators by the user. </p>
	<p><span lang="de">The parameter pragma_token refers to the token &quot;#pragma&quot; 
	triggering this preprocessing hook.</span></p>
	<p>The parameter <tt>filename</tt> contains the file system path of the opened file 
	(this is relative to the directory of the currently processed file or a 
	absolute path depending on the paths given as the include search paths).</p>
</blockquote>
<h3>Interpretation of #pragmas</h3>
<p><strong><a name="interpret_pragma"></a>interpret_pragma</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>    bool <a href="class_reference_ctxpolicy.html#interpret_pragma">interpret_pragma</a>(ContextT <span class="keyword">const</span> &amp;ctx, ContainerT &amp;pending, <br>        <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &amp;option, <br>        ContainerT <span class="keyword">const</span> &amp;values, <br>        <span class="keyword">typename</span> ContextT::token_type<span class="keyword"> const</span> &amp;pragma_token);<br>
</pre>
<blockquote>
  <p>The function <tt>interpret_pragma</tt> is called whenever an unrecognized <tt>#pragma&nbsp;wave&nbsp;...</tt> or operator <tt>_Pragma("wave&nbsp;...")</tt> is found in the input stream.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p>
  <p>The <tt>pending</tt> parameter may be used to push tokens back into the input 
    stream which are to be used as the replacement text for the whole <tt>#pragma&nbsp;wave()</tt> directive. If this sequence is left empty, no replacement takes place, i.e. 
    the interpreted directive is removed from the generated token stream.</p>
  <p>The <tt>option</tt> parameter contains the name of the interpreted pragma.</p>
  <p>The <tt>values</tt> parameter holds the value of the parameter provided to 
    the pragma operator.</p>
  <p>The <tt>pragma_token</tt> parameter contains the actual #pragma token which 
    may be used for extraction of the location information for some error output.</p>
  <p>If the return value is 'false', the whole #pragma directive is interpreted 
    as unknown and a corresponding error message is issued. A return value of 
    'true' signs a successful interpretation of the given #pragma.<br>
  </p>
</blockquote>
<h3>Macro definition </h3>
<p><strong><a name="defined_macro" id="defined_macro"></a>defined_macro</strong></p>
<pre>    <span class="keyword">template</span> &lt;<br>        <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ParametersT, <span class="keyword">
        typename</span> DefinitionT<br>    &gt;<br>    <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#defined_macro">defined_macro</a>(ContextT <span class="keyword">const</span>&amp; ctx, <br>        TokenT <span class="keyword">const</span> &amp;name, <span class="keyword">bool</span> is_functionlike,<br>        ParametersT <span class="keyword">const</span> &amp;parameters, DefinitionT <span class="keyword">const</span> &amp;definition,<br>        <span class="keyword">bool</span> is_predefined);<br>
</pre>
<blockquote>
  <p>The function <tt>defined_macro</tt> is called whenever a macro was defined successfully.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The parameter <tt>name</tt> is a reference to the token holding the macro name.</p>
  <p>The parameter <tt>is_functionlike</tt> is set to true whenever the newly 
    defined macro is defined as a function like macro.</p>
  <p>The parameter <tt>parameters</tt> holds the parameter tokens for the macro
    definition. If the macro has no parameters or if it is a object like
    macro, then this container is empty.</p>
  <p>The parameter <tt>definition</tt> contains the token sequence given as the
    replacement sequence (definition part) of the newly defined macro.</p>
  <p>The parameter <tt>is_predefined</tt> is set to true for all macros predefined 
    during the initialisation pahase of the library.<br>
  </p>
</blockquote>
<p><strong><a name="undefined_macro" id="undefined_macro"></a>undefined_macro</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;<br>    <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#undefined_macro">undefined_macro</a>(ContextT <span class="keyword">const</span>&amp; ctx, TokenT <span class="keyword">const</span> &amp;name);<br>
</pre>
<blockquote>
  <p>The function <tt>undefined_macro</tt> is called whenever a macro definition
    was removed successfully.</p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user.</p>
  <p>The parameter <tt>name</tt> holds the token of the macro which definition was removed.<br>
  </p>
</blockquote>
<p><strong><a name="found_warning_directive" id="found_warning_directive"></a>found_warning_directive</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>    <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_warning_directive">found_warning_directive</a>(ContextT <span class="keyword">const</span>&amp; ctx, <br>        ContainerT <span class="keyword">const</span> &amp;message);<br>
</pre>
<blockquote>
  <p>The function <tt>found_warning_directive </tt> is called whenever a <span class="preprocessor">#warning </span>directive
    has been encountered. This function will be called only if the <tt>BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE</tt> compile time constant was defined to something not equal to zero (see the <a href="compiletime_config.html">Compile Time Configuration</a> for more information). </p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p>
  <p>The parameter <tt>message</tt> references the argument token sequence of the encountered <span class="preprocessor">#warning</span> directive.</p>
  <p>If the return value is <tt>false</tt>, the library throws a preprocessor 
    exception of the type <code>warning_directive</code> (normal execution continues), if the return value is <tt>true</tt> the execution continues as if no <span class="preprocessor">#warning</span> directive has been found and the overall directive is replaced by a single newline. </p>
</blockquote>
<p><strong><a name="found_error_directive" id="found_error_directive"></a>found_error_directive</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>    <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_error_directive">found_error_directive</a>(ContextT <span class="keyword">const</span>&amp; ctx, <br>        ContainerT <span class="keyword">const</span> &amp;message);<br>
</pre>
<blockquote>
  <p>The function <tt>found_error_directive </tt> is called whenever a <span class="preprocessor">#error </span>directive has been encountered. </p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p>
  <p>The parameter <tt>message</tt> references the argument token sequence of the encountered <span class="preprocessor">#error</span> directive.</p>
  <p>If the return value is <tt>false</tt>, the library throws a preprocessor 
    exception of the type <code>error_directive</code> (normal execution continues), if the return value is <tt>true</tt> the execution continues as if no <span class="preprocessor">#error</span> directive has been found, and the overall directive is replaced by a single newline. </p>
</blockquote>
<p><strong><a name="found_line_directive" id="found_line_directive"></a>found_line_directive</strong></p>
<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;<br>    <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#found_error_directive"><strong>found_line_directive</strong></a>(ContextT <span class="keyword">const</span>&amp; ctx, <br>        ContainerT <span class="keyword">const</span> &amp;arguments, <span class="keyword">unsigned int</span> line,<br>        std::string <span class="keyword">const</span>&amp; filename);
</pre>
<blockquote>
  <p>The function <tt>found_line_directive </tt> is called whenever a <span class="preprocessor">#line </span>directive has been encountered. </p>
  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p>
  <p>The parameter <tt>arguments</tt> references the argument token sequence of the encountered <span class="preprocessor">#line</span> directive.</p>
  <p>The parameter <tt>line</tt> contains the recognized line number from the <span class="preprocessor">#line</span> directive.</p>
  <p>The parameter <tt>filename</tt> references the recognized file name from the <span class="preprocessor">#line</span> directive (if there was one given).<br>
  </p>
</blockquote>
<p><strong><a name="emit_line_directive" id="emit_line_directive"></a>emit_line_directive</strong></p>
<pre>
    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> <span class="type">ContextT</span>, <span class="keyword">typename</span> <span class="type">ContainerT</span>&gt;
    <span class="type">bool</span> <span class="function-name">emit_line_directive</span>(<span class="type">ContextT</span> <span class="keyword">const</span>&amp; <span class="variable-name">ctx</span>, <span class="type">ContainerT</span> &amp;<span class="variable-name">pending</span>, 
        <span class="keyword">typename</span> <span class="constant">ContextT</span>::<span class="type">token_type</span> <span class="keyword">const</span>&amp; <span class="variable-name">act_token</span>);
</pre>
<blockquote>
  <p>The function <tt>emit_line_directive</tt> is called whenever a <span class="preprocessor">#line</span> directive
  has to be emitted into the generated output.</p>

<p>The parameter &nbsp;<tt>ctx</tt> is a reference to the context object used for
  instantiating the preprocessing iterators by the user.</p>

<p>The parameter &nbsp;<tt>pending</tt> may be used to push tokens back into the input
stream, which are to be used instead of the default output generated
  for the <span class="preprocessor">#line</span> directive.</p>

  <p>The parameter &nbsp;<tt>act_token</tt> contains the actual <span class="preprocessor">#pragma</span> token, which may
be used for error output. The line number stored in this token can be
    used as the line number emitted as part of the <span class="preprocessor">#line</span> directive.</p>

  <p>If the return value is &nbsp;<tt>false</tt>, a default <span class="preprocessor">#line</span> directive is emitted
by the library. A return value of &nbsp;<tt>true</tt> will inhibit any further
actions, the tokens contained in &nbsp;<tt>pending</tt> will be copied verbatim
    to the output.</p>
</blockquote>

<table border="0">
  <tbody>
    <tr>
      <td width="10"></td>
      <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
      <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/l_arr.gif" border="0" height="19" width="20"></a></td>
      <td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td>
    </tr>
  </tbody>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2011 Hartmut Kaiser<br>
  <br>
  <font size="2">Distributed under the Boost Software License, Version
  1.0. (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt) </font> </p>
<p class="copyright"><span class="updated">Last updated:
  <!-- #BeginDate format:fcAm1m -->Thursday, September 1<span lang="de">8</span>, 2010  
<span lang="de">09</span>:<span lang="de">10</span><!-- #EndDate -->
  </span></p>
</body>
</html>
